Compressing Image Sequences3

The standard dialog component provides three functions you may use to compress an image sequence. The SCCompressSequenceBegin function allows you to start a sequence-compression operation; use the SCCompressSequenceFrame function for each image in the sequence; you end the sequence by calling the SCCompressSequenceEnd function. The standard dialog component manages all of the compression details for you. Your application may have only one sequence-compression operation active on any given connection; naturally, you may have more than one connection active at a time.

If there are no default settings, each of these functions could potentially display the dialog box for sequence-compression operations shown in Figure 2 .

SCCompressSequenceBegin

The SCCompressSequenceBegin function initiates a sequence-compression operation. You supply the first image in the sequence so that the component can determine its spatial and graphical characteristics.



 
pascal ComponentResult SCCompressSequenceBegin 

                                         (ComponentInstance ci, 

                                         PixMapHandle src, const Rect *srcRect, 

                                         ImageDescriptionHandle *desc);

ci: Identifies your application's connection to a standard image-compression dialog component.
src: Contains a handle to the pixel map to be compressed. This pixel map must contain the first image in the sequence.
srcRect: Contains a pointer to a portion of the pixel map to compress. This rectangle must be in the pixel map's coordinate system. If you want to compress the entire pixel map, set this parameter to nil .
desc: Contains a pointer to an image description handle. The standard dialog component creates an image description structure when it compresses the image, and returns a handle to that structure in the field referred to by this parameter. The component sizes the handle appropriately. If you do not want this information, set this parameter to nil .; The returned structure is valid for the entire sequence. The standard dialog component disposes of the handle when you end the sequence by calling the SCCompressSequenceEnd function. Your application must not dispose of this handle by any other means.

RESULT CODES

Memory Manager errors Image Compression Manager errors (from CompressSequenceBegin function)

SCCompressSequenceFrame

The SCCompressSequenceFrame function continues a sequence-compression operation. You must call this function once for each frame in the sequence, including the first frame.



 
pascal ComponentResult SCCompressSequenceFrame 

                                         (ComponentInstance ci, PixMapHandle src, 

                                          const Rect *srcRect, Handle *data, 

                                          long *dataSize, short *notSyncFlag);

ci: Identifies your application's connection to a standard image-compression dialog component.
src: Contains a handle to the pixel map to be compressed.
srcRect: Contains a pointer to a portion of the pixel map to compress. This rectangle must be in the pixel map's coordinate system. If you want to compress the entire pixel map, set this parameter to nil .
data: Contains a pointer to a handle. The standard dialog component returns a handle to the compressed image data in the field referred to by this parameter. The component sizes that handle appropriately for the sequence.; Your application must not dispose of this handle. The standard dialog component disposes of the handle when you end the sequence by calling the SCCompressSequenceEnd function. If you need to lock the handle, be sure to save and restore the handle's state.
dataSize: Contains a pointer to a long integer. The standard dialog component returns a value that indicates the number of bytes of compressed image data that it returns. Note that this value will differ from the size of the handle referred to by the data parameter, because the handle is allocated to accommodate the largest image in the sequence.
notSyncFlag: Contains a pointer to a short integer that indicates whether the compressed frame is a key frame. If the frame is a key frame, the standard dialog component sets the field referred to by this parameter to 0; otherwise, the component sets this field to mediaSampleNotSync . You may use this field to set the sampleFlags parameter of the Movie Toolbox's AddMediaSample function.

RESULT CODES

scUserCancelled

Dialog box canceled--user clicked Cancel

Image Compression Manager errors (from CompressSequenceFrame function)

SCCompressSequenceEnd

The SCCompressSequenceEnd function ends a sequence-compression operation. The standard dialog component disposes of any memory it used to compress the image sequence, including the data and image description buffers. You must call this function once for each sequence you start.



 
pascal ComponentResult SCCompressSequenceEnd 

                                         (ComponentInstance ci);

ci: Identifies your application's connection to a standard image-compression dialog component.